LOGTIME 1.0 Linux and Windows time logging facility Copyright (c) 1996 by Christopher S L Heng. All rights reserved. ---------------------------------------------------------------- $Id: readme.txt 1.3 1996/05/09 11:00:40 chris Exp $ /* CONTENTS -------- INTRODUCTION COPYRIGHT PACKING LIST INSTALLING FOR WINDOWS INSTALLING FOR LINUX CONTACTING THE AUTHOR MORE INFORMATION INTRODUCTION ------------ LOGTIME was designed to allow users to keep track of the amount of time taken and the charges accumulated when logging into an internet service provider ("ISP"). This might be useful if you use an ISP that charges you for the time you take when logged onto your account. LOGTIME has the following features: - It keeps track of time by being called from your login and logout script in your dial-up program. It can, of course, be called manually as well, should your dial-up program not have any means by which you can execute external programs. - Some ISPs charge different rates for connections made during the day and those in the night and/or connections made on a public holiday or weekend and those on a working day. LOGTIME is able to distinguish between such connections and display the appropriate results if configured correctly. - It displays the amount of time you have spent as well as the charges you have accumulated so far. If your ISP provides you with a block of time which you have prepaid, LOGTIME will display the amount of time that you have left for that month (as compared to the prepaid time) or the amount of time in excess of the prepaid time that you have used. - The log file, which contains the record of login/logout times, and the configuration file are compatible between the versions of LOGTIME for Windows and Linux. You can keep the log and configuration files in a place accessible by the LOGTIME for the two systems, and use one set of files for accesses made in both systems! - LOGTIME is configurable: you can change the charges it is to calculate for the time you clock, you can modify the way LOGTIME rounds the time clocked, you can set the days which it is to consider as public holidays, or change the times which it is to consider as working hours. Note that while LOGTIME can give you an idea of the amount of time and cost you have clocked so far, the results supplied by LOGTIME may not agree with those calculated by your ISP. Differences can arise as a result of many reasons: your ISP may start and stop clocking at a different moment than the moment your script calls LOGTIME , your ISP may use a different method to round or truncate sessions that take less than minute, etc. COPYRIGHT --------- Copyright (c) 1996 by Christopher S. L. Heng. All rights reserved. The programs, the accompanying files and documentation are copyrighted (c) 1996 by Christopher S. L. Heng. All rights reserved. For the purpose of this copyright statement, the programs, their accompanying files and documentation are collectively referred to as the "package". You may use and distribute the programs, their accompanying files and documentation free of charge only if you agree to all of the following conditions: 1. All the files that are part of this package must be distributed. 2. The files must not be modified in any way. You may however archive the files using a different archive format if you like, for example, using the LZH format or the TAR format. 3. No additional files may be added to the package. 4. THERE IS NO WARRANTY ON THE PROGRAM AND ITS ACCOMPANYING FILES AND DOCUMENTATION, NOT EVEN THE IMPLIED WARRANTY OF MECHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. YOU AGREE TO BEAR ALL RISKS AND LIABILITIES ARISING FROM THE USE OF THE PROGRAMS AND THE ACCOMPANYING FILES AND DOCUMENTATION AND THE INFORMATION PROVIDED BY THE PROGRAMS AND THE DOCUMENTATION. 5. You may charge a nominal fee to recover the cost of media (such as for the cost of CDROM or diskettes) and copying when distributing this package as long as it is clear that you are not charging for the package itself. If you cannot accept any of the above conditions, you may not use or distribute the program and its accompanying files. If you wish to distribute the package, and are unsure whether your distribution meets the above conditions, please try contacting me, and furnish me all the necessary details so that I can let you know. See also: Contacting the Author PACKING LIST ------------ The following files are included in the LOGTIME package: readme.txt First file you should read logtime.exe Windows version of LOGTIME logtime.hlp Online manual for the Windows version of LOGTIME ctl3d.dll Support file for the Windows version of LOGTIME logtime Linux version of logtime (a.out executable) logtime.1 Manual page for the Linux version of logtime sample.ini Sample configuration file with explanations INSTALLING FOR WINDOWS ---------------------- To install LOGTIME for Windows, simply copy all the LOGTIME files into a directory on your hard disk. For example, if you wish to place LOGTIME in the C:\LOGTIME directory of your hard disk, simply create the directory C:\LOGTIME (you may do this under DOS by typing "MKDIR \LOGTIME" while you are at the C:\> prompt) and copy all the LOGTIME files into that directory (you may do this under DOS by typing "COPY *.* C:\LOGTIME" if your current directory contains the only the LOGTIME files). Next you will need to find some way so that LOGTIME is executed each time you connect to and disconnect from your Internet Service Provider ("ISP"). If you run a winsock package that executes a script file, place a call to logtime -b in your login script file when there is a successful login; and a call to logtime -e in your logout script file when your winsock program logs off from the ISP. If your winsock package does not execute a script file, you need to invoke it manually each time you log in and log out. It might be convenient to associate an item in a Program Manager group with the command logtime -b and place the text "Begin logging" as the description for that item; and an item for the command logtime -e and place the text "End logging" for the description for that item. This way, each time you get a successful connection with your winsock dialer, just double-click the "Begin logging" icon in your Program Manager to start the logging; and once you log out, double-click the "End logging" icon in your Program Manager. The -b parameter to LOGTIME starts the clock to time the session, and the -e parameter to LOGTIME stops the stop clock. If you wish to share the same configuration and data files for both your Linux and Windows system, install LOGTIME for Windows and its accompanying files to a directory that is mounted by Linux. In your Linux SLIP/PPP script, specify that directory using the -D option to the Linux logtime . For more information about this, see Installing for Linux. You need to configure LOGTIME before you can use it in any meaningful way. Run LOGTIME and type F1 and go to the How to Configure LOGTIME for more details. INSTALLING FOR LINUX -------------------- This installation guide assumes that you have managed to get PPP or SLIP working on your system. I assume that you are using the pppd package below. If you use SLIP or a different package, adjust accordingly. At present, the Linux logtime binary requires the a.out shared libraries to be present on your system for it to work. You will need the a.out shared libraries 4.5.26 or later for logtime to work. Note that it is likely that future versions will have both the ELF and a.out binaries. (It is also likely that future versions will require a later version of the a.out shared libraries since I hope to upgrade all the development tools (ie, gcc, libc, etc) on my system.) To install the Linux logtime binary, simply copy it to /usr/bin or /usr/local/bin (or any directory in your path that you fancy). Copy the manual page logtime.1 to your manual directory, such as /usr/man/man1 or /usr/local/man/man1 (whichever is appropriate for your system). Then add logtime to the script file that is executed when a ppp or slip link is established and when the ppp or slip link is disconnected. For a ppp connection that uses pppd, you might, for example, put the following line into your ip-up file: logtime -D /dos/c/logtime -b and the following line into your ip-down file: logtime -D /dos/c/logtime -e Note that the logtime for Linux differs from the LOGTIME for Windows in that the Linux version will search in the LOGTIME directory off the user's home directory by default for the log data files and the configuration file unless you specify otherwise. The Windows version searches for the log data files and configuration file in the directory from which the LOGTIME executable was executed. The difference is because most Unix executables (binaries) live in a common directory like /usr/bin, /usr/local/bin, /bin and the like, whereas Windows executables often live in their own directory. You can cause logtime to search for the log and configuration file in a directory of your choice by specifying that directory in an environment variable LOGTIMEDIR or by overriding it on the command line with the -D option. For example, (LOGTIMEDIR=/dos/d/logtime ; logtime -b) will cause logtime to search in the directory /dos/d/logtime and use the configuration file there and save the current time into the log file located in that directory. And, logtime -D /dos/c/logtime -e will cause logtime to look into the /dos/c/logtime directory for its configuration file and clock the end of the session in a log file located in that directory. The option -b is used to indicate to logtime the start of a session to log. The option -e indicates that the user has logged out and that logtime is to terminate the logging of time for the session. If you wish to share the same configuration and data files for both your Linux and Windows system, install LOGTIME for Windows and its accompanying files to a directory that is mounted by Linux. In your Linux script, specify that directory to logtime. Note that the Linux version will also create the data directory if it does not exist. This applies whether the data directory is the default directory off the user's home directory or specified via the LOGTIMEDIR environment or specified on the command line. This is different from the behaviour of the Windows version. You will need to configure logtime so that it computes time and charges according to the rates set by your Internet Service Provider for your area. To do this create an ASCII text file called logtime.ini in your logtime data directory (the directory you specify with the -D option or the LOGTIMEDIR environment variable or the default in your home directory). WARNING: the text file must be delimited by carriage return-line feed pairs and not the usual Unix line feed newline delimiters. This is because the same text file is read by the Windows LOGTIME.EXE executable. In any case, the Linux logtime also expects the file to have carriage return-line feed pairs. If you have difficulty creating such files under Linux, you might want to create the file under DOS or Windows, or copy the sample.ini file to logtime.ini and change the values accordingly, or configure using the Windows LOGTIME.EXE (recommended). The logtime.ini file is formatted according to the usual formatting rules for Windows 3.1 INI files. The specific variables used by logtime are explained in the sample.ini file. Please refer to that file for details if you are not using the Windows LOGTIME.EXE to configure. You must configure logtime. Otherwise it will have no idea what rates your Internet Service Provider uses, what hours constitute peak and non-peak hours, when the public holidays are, etc. CONTACTING THE AUTHOR --------------------- If you wish to contact me about LOGTIME , you may email me on the Internet via one of the addresses given below (if one of the addresses fail, try the other). Please note that while I generally would like to hear from you if you are using the program, and I certainly would like to know if you discover any bugs in the program, I am under no obligation to fix any bugs. In fact, I make no promises about even replying. My current internet email addresses: cyfheng@singnet.com.sg ChristopherHeng@pobox.org.sg MORE INFORMATION ---------------- The complete manual for LOGTIME is available online. To read the manual, do one of the following: 1. If you are running the Windows version of LOGTIME, start up LOGTIME for Windows and hit the F1 key. 2. If you are running the Linux version of LOGTIME, you may read the manual page for logtime using the following command: man logtime Note that the contents of the Windows help file and the Linux manual page are not identical.